'\" t
.TH cm2_mci 1 "20 August 2007" "Code Manager II"

.SH NAME
mci \- Check in file revisions

.SH SYNOPSIS
mci [\fB--verbose\fP] [\fB--msg\fP \fIM\fP] [\fB--force\fP] [\fB--force-write\fP] 
    [\fB--existing|--allfiles\fP] file|directory ... 

.SH DESCRIPTION
The \fImci(1)\fP utility has two purposes:

.TP 4
.B *
It allows files that are currently under code control and are currently checked out
by the user to be checked back in again.
.TP
.B *
It allows files that are not yet under code control to be initially checked in.
.RE

In each case a message is required. The message can be spread over multiple lines
though most of the \fBCode Manager II\fP tools only show the first line currently.

Following the check in of a file the file will remain present in the directory but
in a read-only status. To edit the file further the \fIcm2_mco(1)\fP command will be 
required.

.SH ARGUMENTS
.TP 8
.B --verbose
Show more information regarding the check-in process.
.TP
.B --msg
Specifies the message to be used to check in the specified files. This is particularly
useful when checking in more than one file that should be given a common message.

If this argument is not supplied the 'interactive' editor mode will be invoked - see the 
\fBEntering Update Comments\fP section below for details.

.TP
.B --force
By default if the name of the file in question matches one of the specified
ignore suffixes for the project it will be ignored by the checkin utility. If this
file should be managed under code control, then specified of the \fB--noignore\fP
flag will override this setting.

This argument can also be used if the file is currenly checked out by 
someone else and you wish to check it back in for them. This is only possible if
you have read access to the checked out version and are able to write to the
directory.

.TP
.B --force-write
Forces the check in of the file when the current project has a \fBPROTECTION\fP setting
of "force-write". If such a \fBPROTECTION\fP setting is present, but this argument is
not specified then the check-out of the file will be aborted.

.TP
.B --existing
If a pattern is specified to match multiple files to check in, then this
flag will ensure that only files that are currently under code control and
checked back in - other files matching the pattern remain outside
code control.

.TP
.B --allfiles
Overwrite the default handling when the arguments include a directory for checking
in files. Normally such an argument would result in the \fB--existing\fP flag
being turned on - resulting in only files that are currently checked out being
checked back in again.

.SH DIRECTORY HANDLING
If a directory is encountered in the list of objects to check back in then the 
handling of the command changes a little. In this instance all files in all 
sub-directories of the given directory are added to the command line and treated
as files to check-back in. However any file that is currently not checked out
will be silently ignored. If just files are specified on the command line a error
would have been given.

If should be noted that any files that are in the list generated match any file
patterns to be ignored they will not be checked back in - unless the \fB--force\fP 
option is also specified on the command line.

Finally as a safety feature finding a directory on the list of objects to handle
will also automatically turn on the \fB--existing\fP argument - ensuring only files
that are currently checked out are checked back in - new files are not. To check in 
new files see the \fIcm2_checkin(1)\fP manual page.

One case that is worthy of consideration is using a statement in a directory such 
as:

.TS
l.
cm2 mci --msg "Initial checkin" *
.TE

From the above it might be implied that the aim here was to check in all files
in the current directory for the first time. This will be indeed true - \fBbut only
when their are no subdirectories!\fP. If there are sub-directories they will be
included in the list of arguments, and as stated above, this will automatically 
turn on the \fB--existing\fP flag - so no new files will be checked in!

To overcome this problem simply add the \fB--allfiles\fP to the command to
handle all files, [even those in sub-directories], and perform initial file checkins
as well.

.SH EXIT CODES
The \fIcm2_mci(1)\fP follows UNIX standard practise:

.TP 4
.B 0
One or more files were successfully checked in or initiated under code control.
.TP
.B >0
An error occured whilst attempting to check in the specified files.

.SH NOTES

.SS Entering Update Comments
The \fBCode Manager II\fP attempts to force the user to enter a comment if the \fB--msg\fP
argument is not specified. In this scenario the use of the environment variable
\fBMEDITOR\fP should be considered. When this is set (to "vi" for example), the
comments are entered via this file. In such cases a dummy file will be shown,
such as:

.TS
l.
#MCI##
#MCI## Please enter comments for checkin of cm2_mci.1.
#MCI## Lines beginning with #MCI## will be discarded.
#MCI## Enter ABORT on a line to abort check in.
#MCI## [Run unset MEDITOR to turn off this functionality]
#MCI##
.TE

The comments should clarify the use of the comment lines.

.TP 8
.B GVIM USERS
If the user intends to use "gvim" as the setting for \fBMEDITOR\fP, then it should be 
specified as "gvim -b" - otherwise the files in question will be checked in before any
comments can be entered!

.SH AUTHOR
The \fBCode Manager II\fP tool set was written by Simon Edwards, Proprius Consulting Ltd, (\fBwww.proprius.co.uk\fP).

.SH SEE ALSO
.BR cm2_checkin(1),
.BR cm2_cpproject(1),
.BR cm2_mco(1),
.BR cm2_munlock(1),
.BR cm2_status(1)

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP.

